home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 551-575 / disk_563 / m2midi / midilib.lzh / docs / bind.doc < prev    next >
Text File  |  1989-06-25  |  8KB  |  258 lines
  1. Bind - Binding routine builder
  2.  
  3. Overview
  4. --------
  5.  
  6. This program takes a standard .fd (function definition) file and
  7. generates a binding library for the functions defined in the .fd file.
  8. The bindings are generated based on a set of rules for a target compiler
  9. defined in a file called "bindfile".  These rules specifiy which
  10. registers need to be preserved, how the arguments are passed on the
  11. stack, and the syntax to call an assembler and a librarian.
  12.  
  13.  
  14. Arc File Contents
  15. -----------------
  16.  
  17.     Bind -- the AutoDoc program
  18.     bind.doc -- this file
  19.     bindfile -- a sample bindfile containing rules for Aztec (small
  20.         code/data and large code/data version) and Lattice.
  21.     midi_lib.fd -- the .FD file for the MIDI Library.  It's included here
  22.            as a sample non-Rom-Kernal library that use to try
  23.            bind on.
  24.     zlib -- simple Amiga object module librarian
  25.     zlib.c -- source code to zlib
  26.  
  27.  
  28. Usage
  29. -----
  30.  
  31. The syntax for Bind is:
  32.  
  33.     Bind [opts] <.fd file>
  34.  
  35.     <.fd file> - name of the function definition file to use as a
  36.          source.  The ".fd" portion may be left off of the name.
  37.          The output library name is derived from the portion of
  38.          the .fd file to the left of the period (e.g.
  39.          midi_lib.fd will generate midi_lib.lib)
  40.  
  41.     opts:
  42.     -a    generate assembly only
  43.     -c    generate object modules only
  44.     -f<s>    specify alternate bindfile
  45.     -o<s>    specify output library name
  46.     -r<s>    specify rule name
  47.     -w<s>    specify work directory
  48.  
  49.  
  50.  
  51. A library is built by first generating an object module for each binding
  52. routine and an LVO definition module.  Each module is created by writing
  53. an assembly file to the work directory and then assembling it.    Once all
  54. the object modules are generated they are collected into a library.
  55. Temporary files (assembly and object) are deleted from the work
  56. directory as soon as they are no longer needed.  The actual invocations
  57. for the assembler and librarian depend on the selected set of rules.
  58.  
  59. Binding rules are defined in a "bindfile".  By default this file is
  60. called bindfile and resides in the current directory or the s:
  61. directory.  An alternate bindfile may be specified with the -f switch.
  62. A bindfile contains entries for target compilers.  Each entry contains
  63. rule definitions that specify how to build a binding routine for the
  64. target compiler.  The syntax is as follows:
  65.  
  66. <target>:
  67.     <rule key> = <value>
  68.     .
  69.     .
  70.     .
  71.     <rule key> = <value>
  72.  
  73. <target>:
  74.     <rule key> = <value>
  75.     .
  76.     .
  77.     .
  78.     <rule key> = <value>
  79.  
  80.     .
  81.     .
  82.     .
  83.  
  84.  
  85. The target name can contain any name but must not contain embedded
  86. spaces.  It should begin in the first column and be terminated with a
  87. colon.    Target name matching is case insensitive.
  88.  
  89. Rule keys must be preceded with white space and spelled exactly as
  90. follows (case is not significant).  They may be placed in any order
  91. within a rule set.
  92.  
  93.     StackOffset = <offset>
  94.  
  95.     Specifies how many bytes preceded arguments in the stack frame
  96.     when the routine first becomes active.    If nothing is pushed on
  97.     the stack between the arguments and the return location (pushed
  98.     by jsr) then <offset> would be 4.  This depends very heavily on
  99.     how the target compiler calls routines.  The default value is 0.
  100.  
  101.  
  102.     SaveRegs = <register set>
  103.  
  104.     This specifies the registers that the compiler expects to have
  105.     preserved.  Use a standard 68000 MOVEM register set here (e.g.
  106.     d2-d7/a2-a5).  The default is to preserve no registers.
  107.     Currently you are not allowed to preserve D0 or A7 this way.  D0
  108.     is where return values from placed by standard Kernal routines.
  109.     A7 is the stack and is automatically preserved.
  110.  
  111.  
  112.     Assembler = <asm syntax>
  113.  
  114.     Specifies the name of the assembler to use and its syntax.  Two
  115.     string substitutions are performed here.
  116.  
  117.         $a - gets replaced by the name of the assembly file
  118.          generated by bind.
  119.  
  120.         $o - gets replaced by the name of the object module that
  121.          should be produced by the assembler.
  122.  
  123.     (e.g. as $a -o $o)  Bind generates assembly files suffixed with
  124.     .asm and expects object files to suffixed by .o.  These suffixes
  125.     are supplied with the $a and $o string substitutions.
  126.  
  127.     The assembler used should be capable of generating a
  128.     non-zero return code on failure in order to shut down bind.
  129.     Both Aztec's as and MCC's assem behave well.
  130.  
  131.     The assembler is loaded using fexecl() so that the current path
  132.     will be searched in order to find the assembler.
  133.  
  134.     The default is no assembler.  This will not permit you to make
  135.     anything other than assembly files.
  136.  
  137.  
  138.     Librarian = <lb syntax>
  139.  
  140.     Specifies the name of the librarian to use and its syntax.  Two
  141.     string substitutions are performed here.
  142.  
  143.         $l - is replaced by the selected name of the output library.
  144.  
  145.         $o - is replaced by the entire list of object modules to
  146.          place in the library.
  147.  
  148.     (e.g. lb $l $o)  By default bind will generate a library name
  149.     based on the .fd file name (e.g. midi_lib.fd becomes
  150.     midi_lib.lib).    You can select another output library name using
  151.     the -o option.    .lib is not automatically attached to the name;
  152.     you need to specify it.
  153.  
  154.     As with the assembler, the librarian should be capable of
  155.     generating a non-zero return code on failure in order.    Aztec's
  156.     lb utility and zlib both work this way.
  157.  
  158.     The default is no librarian.  This will prevent you from
  159.     going beyond the object module stage.
  160.  
  161.  
  162. Comments may be placed in the bindfile if they are preceeded with a
  163. pound sign (#) in the first column (like makefile comments).  Also,
  164. blank lines are considered comments.
  165.  
  166. There is a sample bindfile contained in the .arc file.
  167.  
  168.  
  169. Work files
  170. ----------
  171.  
  172. Work files are placed in the "work directory".  The work directory is
  173. determined in one of two ways.    If none is specified, the directory
  174. associated with the environment variable CCTEMP is used (this is set by
  175. either the Aztec or the ARP set command).  You may override this by
  176. using the -w switch to specify any directory.  The default is the
  177. current directory.
  178.  
  179. Work files are automatically deleted when they are no longer needed or
  180. when the program fails or is aborted using Control-C.
  181.  
  182.  
  183. The options
  184. -----------
  185.  
  186. -a causes bind to stop after generating the assembly code for the
  187. bindings.  They appear in the work directory.
  188.  
  189. -c causes bind to assemble the modules that it generates but leave just
  190. the object modules without making a library.
  191.  
  192. -f allows you to specify some other file to use as a bindfile.    The
  193. default bindfile may exist in the current directory or in the s:
  194. directory.
  195.  
  196. -o allows you to specify another name for the output library.  The
  197. default is made by replacing .fd in the source file name with .lib.  A
  198. file comment is set for the output library indicating which rules were
  199. used to create it.
  200.  
  201. -r specifies a rule name.  The default is to use the first rule in the
  202. bind file.
  203.  
  204. -w specifies an alternate work directory.
  205.  
  206.  
  207. Tech info
  208. ---------
  209.  
  210. The program was compiled using Aztec C3.4B.  Everything described works.
  211. At the very least this can be used to generate bindings for Aztec (any
  212. model) and Lattice.
  213.  
  214. Compilers that don't use A7 for a stack, don't return values in D0, pack
  215. the arguments in reverse order, or require that the bindings pop
  216. arguments off the stack are not currently supported by Bind.  This may
  217. change if there is demand for this and the appropriate technical data is
  218. available.
  219.  
  220. .fd files are not described in this document.
  221.  
  222.  
  223. zlib
  224. ----
  225.  
  226. This is a quick and dirty means of generating a Lattice (Amiga) object
  227. module library.  These appear to be little more than a concatenation of
  228. the constituent object modules.  So this program simply joins all of the
  229. files specified into one file.    Its syntax is:
  230.  
  231.     zlib <out> <source>...
  232.  
  233. The source code is included.
  234.  
  235. (btw AmigaDOS (or ARP) join command doesn't work since it is limited to
  236. only 10 (I think) files)
  237.  
  238.  
  239. Last words
  240. ----------
  241.  
  242. There were several inspirations for this program.  I was requested to
  243. make an .fd file for the MIDI Library and also someone told me that the
  244. Aztec bindings for the MIDI Library failed with Lattice (mainly because
  245. Lattice expects A6 to be preserved and Aztec doesn't).  Also, I got
  246. tired of waiting for C bindings for C. Heath's ARP library and hopefully
  247. this will speed things along.
  248.  
  249. Bind is copyright 1987 by Pregnant Badger Software, but feel free to
  250. distribute it without profit.
  251.  
  252.     Bill Barton
  253.  
  254.     Bix: peabody
  255.     delphi: bbarton
  256.     plink: peabody
  257.  
  258.